Skip to content

docs: add CONTRIBUTING.md with contributors ladder#235

Merged
mrizzi merged 1 commit into
mainfrom
worktree-TC-5079
Jul 7, 2026
Merged

docs: add CONTRIBUTING.md with contributors ladder#235
mrizzi merged 1 commit into
mainfrom
worktree-TC-5079

Conversation

@mrizzi

@mrizzi mrizzi commented Jul 6, 2026 •
edited by sourcery-ai Bot
Loading

Copy link
Copy Markdown
Collaborator

Summary

  • Add CONTRIBUTING.md at repo root with four-tier contributors ladder (Contributor/Read, Reviewer/Write, Maintainer/Maintain, Owner/Admin)
  • Document promotion criteria (hybrid: ~3 months sustained quality + maintainer judgment), demotion policy (~1 year inactivity), and current contributors
  • Document issue workflow (GitHub Issues for external, Jira for internal), fork-and-PR model, and branch protection rules

Implements TC-5079

Test plan

  • Verify CONTRIBUTING.md renders correctly on GitHub (headings, tables, links)
  • Verify a new contributor can understand how to file an issue or submit a PR within 5 minutes of reading

🤖 Generated with Claude Code

Summary by Sourcery

Add a CONTRIBUTING guide that formalizes contributor roles, governance, and workflows for issues, pull requests, and branch protection.

Documentation:

  • Introduce CONTRIBUTING.md documenting the contributor ladder, promotion/demotion policies, and current project contributors.
  • Document external and internal issue reporting workflows and the fork-and-PR contribution process, including review and merge requirements.
  • Describe main branch protection rules and required approvals/CI for merges.

@sourcery-ai

sourcery-ai Bot commented Jul 6, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Reviewer's Guide

Adds a CONTRIBUTING.md at the repo root that defines the contributor ladder, governance (promotion/demotion), and contribution workflows (issues, PRs, branch protection) for the project.

Flow diagram for new fork-and-PR contribution workflow

flowchart LR
  A[Contributor forks repository] --> B[Contributor creates branch in fork]
  B --> C[Contributor implements changes]
  C --> D[Contributor references GitHub Issue in PR]
  D --> E[Contributor opens PR against main]
  E --> F[Reviewer reviews and approves PR]
  F --> G[CI pipeline passes]
  G --> H[Maintainer_or_Owner merges PR]

  style A fill:#e3f2fd,stroke:#1e88e5
  style F fill:#e8f5e9,stroke:#43a047
  style H fill:#fff3e0,stroke:#fb8c00
Loading

File-Level Changes

Change Details Files
Introduce CONTRIBUTING.md documenting contributor roles, governance policies, and contribution workflows.
  • Define a four-tier contributors ladder mapped to GitHub repository roles with associated capabilities.
  • List current contributors and their tiers for project governance transparency.
  • Specify promotion criteria, nomination/approval flow, and demotion policy for inactive contributors.
  • Document separate issue reporting flows for external (GitHub Issues) and internal (Jira) contributors.
  • Describe the fork-and-PR development model, including Conventional Commits and review/merge requirements.
  • Outline branch protection rules for the main branch, including required reviews, passing CI, and approval thresholds.
 CONTRIBUTING.md
Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

sourcery-ai[bot]
sourcery-ai Bot reviewed Jul 6, 2026
View reviewed changes

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey - I've left some high level feedback:

  • The GitHub Issues link uses a ../../issues relative path from the repo root, which is unusual and could be fragile; consider switching to a more standard relative or absolute link (e.g. ./issues or the full repo URL) to avoid navigation issues.
  • The "Current Contributors" table hard-codes specific names and tiers, which can easily become stale; you might want to either describe how this list is maintained or link to a source of truth (e.g. GitHub teams/roles) instead of embedding it directly.
Prompt for AI Agents 
Please address the comments from this code review:

## Overall Comments
- The GitHub Issues link uses a `../../issues` relative path from the repo root, which is unusual and could be fragile; consider switching to a more standard relative or absolute link (e.g. `./issues` or the full repo URL) to avoid navigation issues.
- The "Current Contributors" table hard-codes specific names and tiers, which can easily become stale; you might want to either describe how this list is maintained or link to a source of truth (e.g. GitHub teams/roles) instead of embedding it directly.
Sourcery is free for open source - if you like our reviews please consider sharing them ✨
Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.

@mrizzi mrizzi requested a review from ruromero July 6, 2026 15:34
@mrizzi

mrizzi commented Jul 6, 2026

Copy link
Copy Markdown
Collaborator Author

[sdlc-workflow/verify-pr] Re: @sourcery-ai[bot] review — two suggestions classified:

  1. GitHub Issues link format (../../issues): Classified as suggestion — this proposes an alternative link format; CONVENTIONS.md documents no link format convention and no established codebase pattern exists. The ../../issues relative path is a well-established GitHub Markdown convention that correctly resolves when rendered. No sub-task created.

  2. Hardcoded contributors table: Classified as suggestion — this proposes describing maintenance or linking to a source of truth; CONVENTIONS.md documents no contributor-list maintenance convention and no established codebase pattern exists. The task explicitly required listing specific names and tiers. No sub-task created.

@mrizzi

mrizzi commented Jul 6, 2026

Copy link
Copy Markdown
Collaborator Author

Verification Report for TC-5079 (commit 2fdadc8)

Check Result Details
Review Feedback PASS 2 suggestions from sourcery-ai[bot]; no code change requests
Root-Cause Investigation N/A No sub-tasks created
Scope Containment PASS PR touches exactly CONTRIBUTING.md — matches task spec
Diff Size PASS 103 lines in 1 new file — proportionate for contributors ladder doc
Commit Traceability PASS Commit 2fdadc8 includes "Implements TC-5079"
Sensitive Patterns PASS No secrets or credentials in added lines
CI Status PASS All 3 checks pass (Plugin Validation, Skill Lint, Sourcery)
Acceptance Criteria PASS 8 of 8 criteria met
Test Quality N/A No test files in PR; Eval Quality: N/A
Test Change Classification N/A No test files in PR
Verification Commands N/A No verification commands specified

Overall: PASS

All checks pass. The PR creates CONTRIBUTING.md at repo root with all seven required sections matching the task's acceptance criteria. Two bot suggestions (link format, hardcoded names) were classified and retained as suggestions — neither matches a documented convention or established codebase pattern.

This comment was AI-generated by sdlc-workflow/verify-pr v0.12.2.

ruromero
ruromero approved these changes Jul 7, 2026
View reviewed changes

@ruromero ruromero left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is a key step forward

ruromero
ruromero reviewed Jul 7, 2026
View reviewed changes
Comment thread CONTRIBUTING.md Outdated
@mrizzi
docs: add CONTRIBUTING.md with contributors ladder
7617ab9 
Define four-tier contributors ladder (Contributor/Reviewer/Maintainer/Owner)
mapped to GitHub repository roles, promotion criteria with hybrid model,
demotion policy, issue/PR workflows, and branch protection rules.

Implements TC-5079

Assisted-by: Claude Code
@mrizzi mrizzi force-pushed the worktree-TC-5079 branch from c679070 to 7617ab9 Compare July 7, 2026 07:33
@mrizzi

mrizzi commented Jul 7, 2026

Copy link
Copy Markdown
Collaborator Author

Verification Report for TC-5079 (commit 7617ab9)

Check Result Details
Review Feedback PASS 1 code change request (already fixed), 2 suggestions retained; no sub-tasks needed
Root-Cause Investigation N/A No sub-tasks created
Scope Containment PASS PR touches exactly CONTRIBUTING.md — matches task spec
Diff Size PASS 103 lines in 1 new file — proportionate for contributors ladder doc
Commit Traceability PASS Commit 7617ab9 includes "Implements TC-5079"
Sensitive Patterns PASS No secrets or credentials in added lines
CI Status PASS All 3 checks pass (Plugin Validation, Skill Lint, Sourcery)
Acceptance Criteria PASS 8 of 8 criteria met
Test Quality N/A No test files in PR; Eval Quality: N/A
Test Change Classification N/A No test files in PR
Verification Commands N/A No verification commands specified

Overall: PASS

All checks pass. Reviewer feedback from ruromero (naming inconsistency in contributors table) was addressed in the squashed commit. Two sourcery-ai bot suggestions (link format, hardcoded names) remain as suggestions — neither matches a documented convention.

This comment was AI-generated by sdlc-workflow/verify-pr v0.12.2.

@mrizzi mrizzi merged commit c21ca01 into main Jul 7, 2026
3 checks passed
@mrizzi mrizzi deleted the worktree-TC-5079 branch July 7, 2026 08:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ruromero ruromero ruromero approved these changes
@sourcery-ai sourcery-ai[bot] sourcery-ai[bot] left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@mrizzi @ruromero